home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Other Langs / Tickle-4.0 (tcl) / library / help / tcl / variables / upvar < prev   
Encoding:
Text File  |  1993-10-26  |  2.3 KB  |  49 lines  |  [TEXT/$Tcl]
  1.  
  2.           upvar ?level? otherVar myVar ?otherVar myVar ...?
  3.  
  4.  
  5.      DESCRIPTION
  6.           This command arranges for one or more local variables in the
  7.           current procedure to refer to variables in an enclosing pro-
  8.           cedure call or to global variables.  Level may have  any  of
  9.           the  forms  permitted  for  the  uplevel command, and may be
  10.           omitted if the first letter of the first otherVar isn't # or
  11.           a  digit  (it  defaults  to 1).  For each otherVar argument,
  12.           upvar makes the variable by that name in the procedure frame
  13.           given by level (or at global level, if level is #0) accessi-
  14.           ble in the current  procedure  by  the  name  given  in  the
  15.           corresponding  myVar argument.  The variable named by other-
  16.           Var need not exist at the time of  the  call;   it  will  be
  17.           created  the  first  time  myVar is referenced, just like an
  18.           ordinary variable.  Upvar may only be  invoked  from  within
  19.           procedures.   MyVar may not refer to an element of an array,
  20.           but otherVar may refer to an array element.   Upvar  returns
  21.           an empty string.
  22.  
  23.           The upvar command simplifies the implementation of  call-by-
  24.           name procedure calling and also makes it easier to build new
  25.           control constructs as Tcl procedures.  For example, consider
  26.           the following procedure:
  27.  
  28.                proc add2 name {
  29.                    upvar $name x
  30.                    set x [expr $x+2]
  31.                }
  32.  
  33.           Add2 is invoked with an argument giving the name of a  vari-
  34.           able,  and  it  adds  two  to  the  value  of that variable.
  35.           Although add2 could  have  been  implemented  using  uplevel
  36.           instead  of upvar, upvar makes it simpler for add2 to access
  37.           the variable in the caller's procedure frame.
  38.  
  39.           If an upvar variable is unset (e.g. x in  add2  above),  the
  40.           unset  operation  affects  the variable it is linked to, not
  41.           the upvar variable.  There is no way to unset an upvar vari-
  42.           able except by exiting the procedure in which it is defined.
  43.           However, it is possible to retarget  an  upvar  variable  by
  44.           executing another upvar command.
  45.  
  46.  
  47.      KEYWORDS
  48.           context, frame, global, level, procedure, variable
  49.